The VideoToolbox is a collection of two hundred C subroutines and several demo and utility programs that I and others have written to do visual psychophysics with Macintosh computers. It's free and may not be sold without permission. It should be useful to anyone who wants to present accurately specified visual stimuli or use the Mac for psychometric experiments. The text file "Video synch" discusses all the ways of synchronizing programs to video displays and the many pitfalls to avoid. The TimeVideo application checks out the timing of all video devices in anticipation of their use in critical real-time applications, e.g. movies or lookup table animation. Low-level routines control video timing and lookup tables, display real-time movies, and implement the luminance-control algorithms suggested by Pelli and Zhang (1991). In particular, GetPixelsQuickly and SetPixelsQuickly peek and poke pixels in bitmaps and pixmaps, CopyBitsQuickly copies bit/pixmaps to the screen, and SetEntriesQuickly and GDSetEntries load the screen's color lookup table, all without any of QuickDraw's color translations. High-level routines help analyze psychophysical experiments (e.g. graphing or maximum-likelihood fitting of psychometric data). Assign.c is a runtime C interpreter for C assignment statements, which is useful for controlling experiments and sharing calibration data. This collection has been continually updated since 1991. Many colleagues have indicated that they are using the software in their labs. Documentation is in the source files themselves. Many of the routines are Mac-specific, but some very useful routines, e.g. the luminance-control, statistics, maximum-likelihood fitting algorithms, and the runtime interpreter are written in Standard C and will work on any computer. Those wishing to acknowledge use of the VideoToolbox software might cite:
Pelli, D. G. and Zhang, L. (1991) Accurate control of contrast on microcomputer displays. Vision Research, 31, 1337-1350. Reprints are available.
PowerPC & 680x0:
All the software was written and tested on 680x0 machines. Happily, Scott B. Stevenson <stevenso@garnet.berkeley.edu> reports that TimeVideo, which exercises most of the tricky code, runs fine (by 680x0 emulation) on his new Power Macintosh 8100/80, and I find the same on my 6100/60. I haven't yet tried compiling the VideoToolbox to run as native code on the Power PC--I just received the MetroWerks CodeWarrior Gold--but I'm hoping that very little change will be required.
AVAILABILITY:
The VideoToolbox software is continually updated. To get the latest version, just send me your email or postal address, and I'll send it to you. Or download "video-toolbox" electronically from a public archive:
Log in as "anonymous"; any password will do. If you can't do ftp, you can request a file by email; for instructions send a query to Info-Mac-Request@sumex-aim.stanford.edu. (Or, if you're a member of CompuServe, download VIDEOT.SEA from Library 4 "C and Pascal" in the MacDev forum.) To get future versions automatically, just send me your email address. Each time I post a new version of the VideoToolbox to the Info-Mac Archives, I email a copy to everyone on the subscription list.
The ISR Video Attenuator is a commercial product. Ordering instructions are in the "Video attenuator" file. I have no financial involvement in the ISR Video Attenuator.
AUTHORS:
Adobe (ATMInterface.c and ATMInterface.h)
Apple (TrapAvailable.c, Zoom.c, IsCmdPeriod.c)
Philipp Biermann ("Multisync Sense Pins.note")
David Brainard (a dozen or so routines in Assign.c, one in GDOpenWindow.c)
David Brainard & jms (GetTimeDateString.c)
EJ Chichilniski (SetFileInfo.c)
Raynald Comtois (SetEntriesQuickly.c)
Bart Farell (several routines in SetOnePixel.c and SetPixelsQuickly.c)
Bill Haake (SetEntriesQuickly.c)
Mike Kahl (CopyQuickDrawGlobals.c, kbhit.c)
Joseph Laffey (GetVersionString.c)
Peter Lennie (SetEntriesQuickly.c)
J.N. Little & jmb (ReadMATLABFile.c)
Jamie R. McCarthy (IsCmdPeriod.c)
Izumi Ozhawa (CVNetConvert in the Utilities folder)
Denis Pelli (most of the routines)
SPLAsh Resources (HideMenuBar.c and SetMouse.c)
Dave Radcliffe (FlushCacheRange.c)
Evan Relkin (kbhit.c)
Mike Schechter (PixMapToPICT.c)
Preeti Verghese (GetVoltage.c)
Detailed attribution appears in each file. Please advise of any errors or omissions.
MATLAB:
David Brainard (brainard@condor.psych.ucsb.edu) is presently creating interface files that make it easy to use the VideoToolbox from within MATLAB. If you're interested, contact him. Also see VideoToolboxMATLAB.c in VideoToolboxSources.
GETTING STARTED:
Try the demos: Sandstorm, Grating, FlickeringGrating, Filter, and TimeVideo. TimeVideo times all of your displays, telling you how quickly you can show movies and do lookup table animation. Read "Video synch" and "Advice".
You'll want the VideoToolboxSources folder to be included in the THINK C search path, so that your projects won't include explict file directory paths (including your disk's name) that will break if you transfer everything to a differently named disk. The simplest way to achieve that is to place the entire VideoToolbox inside your THINK C folder. (The Symantec documents say this is a no-no, but it works fine. If you have THINK C 7 then an equally good alternative is to place the VideoToolbox folder outside the THINK C folder--or to shield the folder from the search path by putting parentheses around it "(VideoToolbox)"--and to place an alias to the VideoToolboxSources folder inside the THINK C Aliases folder.) Don't copy source files to your projects; just "Add" them using the THINK C Source menu. That will make it easy to update the VideoToolbox.
Follow the instructions in VideoToolbox.c to precompile "VideoToolbox.h" to recreate the precompiled header "VideoToolbox.pre", since it must be produced by your version of the compiler. (If you're producing an external code resource for MATLAB then use VideoToolboxMATLAB.c instead.)
All the programs that do accurate luminance control use the monitor-calibration data stored in LuminanceRecord1.h or LuminanceRecord2.h (the number is a screen number, similar--but not identical--to the number that appears in the Monitors control panel). These calibration files describe my monitors (Apple High-Resolution Monochrome), and, naturally, before doing any serious data collection you should replace these files with ones that describe your own monitors. Use the CalibrateLuminance program. You'll need a photometer.
NUMERICAL RECIPES IN C:
A few programs in the VideoToolbox (CalibrateLuminance.c, PsychometricFit.c, and Quick3) use the (very handy) Numerical Recipes software and book. Required changes to these routines are described in the "Improve Numerical Recipes" document in the Notes folder. I have included pre-compiled CalibrateLuminance and Quick3 applications for users that don't have the Numerical Recipes. The Numerical Recipes C Set for Macintosh (main book, example book, and disk) costs $90 from:
Cambridge University Press
Orders Department
110 Midland Avenue
Port Chester, NY 10573
1-(800)-227-0247
VERSION OF THINK C:
I suggest that you upgrade to THINK C 7.01. (Symantec provides a free upgrade from version 6.) Version 7.01 is hardly changed from version 6.01, basically a slight enhancement of the user interface of the Symantec Project Manager, and fixing a few bugs in the THINK C compiler. (There are a few extra things--AppleScript support and Apple's Universal Headers--that are useful to THINK C users, but which you'll get only if you pay for the full Symantec C++ 7 package.) In a pinch, you can use THINK C 5, but the upgrade from 5 to 7 is inexpensive and improves the user interface significantly. You cannot use the VideoToolbox with any version of THINK C older than 5. The VideoToolbox includes multiple versions of each THINK C project. Projects whose names end in ".π5" are in THINK C version 5 format, ".π6" are in version 6 format, and ".π" are in version 7 format. Each version of THINK C will read older-format project files (converting them to the new format), but won't read newer formats. (E.g. THINK C 5 will say "Unknown error ID=-192" if you try to open a version 6 project.)
It appears that Symantec is basically dropping THINK C, since it hasn't changed (significantly) since version 5, and since they haven't announced any plans to port it to the PowerPC. (I've also heard that none of the authors work for them any longer.) Symantec is concentrating on C++ (which is based on Zortech C++, not THINK C). I've just received MetroWerks CodeWarrior Gold, which provides both C and C++ on both 680x0 and PowerPC Macs and has gotten rave reviews.
BUGS & SUGGESTIONS:
It's unlikely that you'll find any bugs, but if you do, please send me email so we can fix 'em. Suggestions and code donations (i.e. C routines to be included in the VideoToolbox, possibly in modified form, with full attribution) are warmly appreciated.
denis_pelli@isr.syr.edu
NOT MULTIFINDER FRIENDLY:
Walt Makous writes, "I ran Sandstorm by clicking on the icon for the application, interrupted it by clicking outside the window, and then resumed it by clicking on the window again. This locks the keyboard so that the only way I can get back control is by using the programmer's switch." REPLY: Alas, I've never had any need to write polite applications that gracefully share the computer with other applications. Experiments always seem to deserve hogging it all. The Sandstorm demo allows you to invoke other applications, because it doesn't obscure the whole window, but it doesn't act like a good citizen in paying attention to the messages it gets from the Finder about what happened. (I would go ahead and make the demos multifinder-friendly if I knew how, but it has seemed worth learning just for the sake of the demos.)
COPYBITS & COPYBITSQUICKLY:
CopyBits is one of Apple's more impressive efforts. It's powerful and fast. For my purposes its only drawback is that I haven't always been able to prevent it from doing color translations. (A long time ago it used to be slow, but that's history.) So I wrote CopyBitsQuickly to copy images without color translations. (At present CopyBitsQuickly is approximately the same speed as CopyBits.) However, I recently discovered that Apple's Inside Mac VI documents a new bit in the Color Table that can be used to prevent color translations. The new VideoToolbox routine MakeColorTableExplicit() will set that bit for you in any window's color table. More importantly, GDOpenWindow and AddExplicitPalette() now automatically call MakeColorTableExplicit, so that, when recompiled with this new VideoToolbox, your old programs will automatically acquire this new feature. The consequence of all this is that you may no longer need CopyBitsQuickly, as CopyBits will now usually comply with your request to copy slavishly without color translation. However, I still do seem to run into a few recalcitrant cases, which defy my understanding of Apple's documentation, where I still need to use CopyBitsQuickly to eliminate color translation. Getting CopyBits to do what you want is tricky, so here's some sample code. Note that, unlike CopyBitsQuickly, CopyBits cares what the foreground and background colors are set to--they should be black and white unless you want to "colorize"--and it uses the current device's color tables in association with the destination pix/bitmap, so you should normally set the foreground and background colors and the device before calling CopyBits, as in this example.
if(error)PrintfExit("%s line %d: CopyBits error %d\n"
,__FILE__,__LINE__,error);
}
BLOCKMOVEDATA:
BlockMoveData is a new (as of System Update 3.0 to System 7.1) variant of
BlockMove that omits cache flushing. Calling BlockMoveData() on earlier versions
of the operating system will invoke plain old BlockMove(). BlockMove is coded in each computer's ROM to implement the fastest possible move. E.g. it uses the MOVE16 instruction on the 68040 processor. It may be faster than the generic code that most C compilers produce. When the Quadra's were released, Apple added code to the BlockMove trap to flush the instruction cache each time BlockMove was called, just in case the move was copying instructions that were in the cache. However, flushing the cache everytime you call BlockMove sacrifices the speed benefit of the cache, making it less advantageous to call BlockMove. In System Update 3.0 Apple finally gave developers a way of telling BlockMove not to flush the cache. You call BlockMoveData instead. However, if run on computers lacking System Update 3.0 the flag bit distinguishing BlockMoveData from the old BlockMove will be ignored and the cache will be flushed, which will slow you down. BlockMoveData() is defined in Apple's Memory.h in Apple's new Universal Header files, but is not defined in pre-Universal header files. VideoToolbox.h tests for that case and, if necessary, defines BlockMoveData, so that you may use it freely.
DISCLAIMER (included at the request of the MacPsych archive):
The VideoToolbox is provided "as is" without warranty of any kind. Denis Pelli, Syracuse University, SCiP, the operators of MacPsych, and St. Olaf College make no claims concerning the accuracy or correctness of the computer code contained in, or the results of the use of VideoToolbox. The entire risk as to the results and performance of VideoToolbox is assumed by you. If the VideoToolbox is defective you, and not Denis Pelli, Syracuse University, SCiP, the operators of MacPsych, or St. Olaf College assume the entire cost of all necessary servicing, repair or correction.
